-
Notifications
You must be signed in to change notification settings - Fork 4.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Block Styles: Extend block style variations as mechanism for achieving section styling #57908
Conversation
2ab4d24
to
ae56a2e
Compare
ae56a2e
to
1949ae1
Compare
This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress. If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged. If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack. Thank you! ❤️ View changed files❔ lib/block-supports/block-style-variations.php ❔ phpunit/block-supports/block-style-variations-test.php ❔ phpunit/data/themedir1/block-theme-child-with-block-style-variations/style.css ❔ phpunit/data/themedir1/block-theme-child-with-block-style-variations/styles/block-style-variation-a.json ❔ phpunit/data/themedir1/block-theme-child-with-block-style-variations/theme.json ❔ phpunit/data/themedir1/block-theme/styles/block-style-variation-a.json ❔ phpunit/data/themedir1/block-theme/styles/block-style-variation-b.json ❔ lib/class-wp-theme-json-gutenberg.php ❔ lib/class-wp-theme-json-resolver-gutenberg.php ❔ lib/load.php ❔ phpunit/class-wp-theme-json-resolver-test.php |
Size Change: -422 B (-0.02%) Total Size: 1.74 MB
ℹ️ View Unchanged
|
e6ba6a7
to
79f5765
Compare
08be716
to
fb14f6b
Compare
Testing this now: registering styles via PHP is working as expected but I can't get it to work by adding a "variations" section to TT4's
under styles > blocks, not sure if that's right? |
Thanks for giving this a run @tellthemachines 👍
This is a known issue flagged by @richtabor a few days ago. The issue is there is no automatic registration of block style variations defined in a theme style variation. It currently relies on the block style variation being registered either by the primary theme (e.g. standalone partial theme.json file under /block-styles) or through the PHP I've been AFK recently but am just now picking this back up. So automatic registration of theme style variations should be implemented here soon. What might delay that though is we need to decide if theme style variation definitions of block style variations, should completely replace those defined by the theme or be merged as per about all other Global Styles. |
I'd lean towards merging to start. Reasoning is you might have variations that just change certain characteristics but not others e.g. you want dark background of parent variation but border radius of child. It's a little more flexible. |
Thanks for the quick feedback on that @SaxonF 🚀 The current approach in this PR is to merge any block style variation definitions. When a theme style variation is applied, its data is basically copied into the user's Global Styles. This includes the new There is a new filter that resolves these definitions under their respective block types within the user origin. That process honours any current tweaks a user has made to a block style variation for the current theme (including theme style variation). That side of it is working ok from recent testing. The one catch is how a theme style variation might opt out of a block style variation defined by the primary theme. We might be able to allow the theme style variations to set the block style variation it wants to opt out of to FWIW, the merging of variation styles is also in line with some other ongoing conversations around how settings should be merged across origins. Moving forward, I don't think beginning with a merge-based approach hurts us long term. Any early adopters who would have preferred the "replacement" approach can just define complete overrides for the block style variations within a theme style variation. By that I mean, any styles set on the original variation would have a matching one in the theme style variation version. If we then later moved to a complete replacement of block style variations with those in the theme style variation, those early definitions would only have a few extra styles defined that could potentially be removed. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This looks super promising!
It's cool that editing a shared variation in global styles for a particular block works, applying the edited styles to just that block. Might there also be need for a UI to edit the shared variation for all blocks simultaneously?
Flaky tests detected in a24faaf. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/9263075329
|
48a9132
to
164586d
Compare
I think this PR is getting closer to being ready to move out of draft status but there are a few aspects to it I'd like to flag and see if there are some better approaches.
Update: As flagged in #57908 (comment), the Maintaining style load order for editor overrides
With zero specificity styles, the load order is key to the cascade functioning correctly. Before this PR, This is complicated further by the need to be able to apply variations to blocks at different levels in the hierarchy, in different orders. Achieving the desired behaviour, required passing along data that indicated which applications of variations occurred within the inner blocks. This meant that if an existing variation was being changed in the editor, its style overrides could be updated but any overrides for inner variations would be kept/moved after the parent in the load order. While this would already be the case for an existing application of a variation, a new entry in the To be able to keep the variation IDs predictable and aligned with the generated stylesheet for the variation, it turned out the Merging The requirement to support block style variation definitions from within a theme style variation meant that the variation definitions would live at the @youknowriad and @ellatrix, if you can spare some time, it would be great to get your thoughts, suggestions, and wisdom on this PR 🙏 |
a694f89
to
1c8b54b
Compare
Update here on my latest understanding of the issue - https://github.com/WordPress/wordpress-develop/pull/6271/files#r1619805687. I don't think the error is an immediate concern, as the core backport for sections styling resolves the issue. Most important thing is to get the backport committed. There's some conversation required around how Gutenberg will extend the theme json when implementing new features in the future though. |
Nice sleuthing @talldan 🕵️
Agreed. As far as this PR and feature are concerned, once the backport is merged, I think we're good. |
Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This is done by extending block style variations to apply to nested blocks. See WordPress/gutenberg#57908. Fixes #61312. Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong. git-svn-id: https://develop.svn.wordpress.org/trunk@58264 602fd350-edb4-49c9-b593-d223f7449a82
Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This is done by extending block style variations to apply to nested blocks. See WordPress/gutenberg#57908. Fixes #61312. Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong. Built from https://develop.svn.wordpress.org/trunk@58264 git-svn-id: http://core.svn.wordpress.org/trunk@57727 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This is done by extending block style variations to apply to nested blocks. See WordPress/gutenberg#57908. Fixes #61312. Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong. Built from https://develop.svn.wordpress.org/trunk@58264 git-svn-id: https://core.svn.wordpress.org/trunk@57727 1a063a9b-81f0-0310-95a4-ce76da25c4cd
…g section styling (WordPress#57908) Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org> Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org> Co-authored-by: ramonjd <ramonopoly@git.wordpress.org> Co-authored-by: talldan <talldanwp@git.wordpress.org> Co-authored-by: youknowriad <youknowriad@git.wordpress.org> Co-authored-by: ellatrix <ellatrix@git.wordpress.org> Co-authored-by: SaxonF <saxonafletcher@git.wordpress.org> Co-authored-by: richtabor <richtabor@git.wordpress.org> Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org> Co-authored-by: cbirdsong <cbirdsong@git.wordpress.org> Co-authored-by: bacoords <bacoords@git.wordpress.org> Co-authored-by: getdave <get_dave@git.wordpress.org> Co-authored-by: colorful-tones <colorful-tones@git.wordpress.org> Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org> Co-authored-by: andrewserong <andrewserong@git.wordpress.org> Co-authored-by: kevin940726 <kevin940726@git.wordpress.org> Co-authored-by: ajlende <ajlende@git.wordpress.org> Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org> Co-authored-by: scruffian <scruffian@git.wordpress.org>
Dev Note - Section Styles (draft)In WordPress 6.6, Section Styles simplify the process of styling individual sections of a webpage by offering users a one-click application of curated styles, eliminating the need for repetitive manual configuration. What's Changed?Section-based styling has been enabled by extending the existing Block Styles feature (aka block style variations) to support styling inner elements and blocks. These enhanced block style variations can even be applied in a nested fashion due to uniform CSS specificity ( In addition, block style variations can now be:
UsageRegistration of Block Style VariationsThe block style variations that can be defined and manipulated through Global Styles are limited to those that have been registered with the Any unregistered block style variation defined within a theme.json partial with be automatically registered. Outlined below are three approaches to registering extended block style variations. The approaches leveraging theme.json definitions will automatically register the block style variation with the Defining Block Style VariationsOutlined below are recommended approaches to registering extended block style variations. Theme.json Partial FilesWith the extension of block style variations to support inner element and block type styles, they essentially are their own theme.json file much like theme style variations. As such, block style variations also reside under a theme's A new {
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Variation A",
"slug": "variation-a",
"blockTypes": [ "core/group", "core/columns", "core/media-text" ],
"styles": {
"color": {
"background": "#eed8d3",
"text": "#201819"
},
"elements": {
"heading": {
"color": {
"text": "#201819"
}
}
},
"blocks": {
"core/group": {
"color": {
"background": "#825f58",
"text": "#eed8d3"
},
"elements": {
"heading": {
"color": {
"text": "#eed8d3"
}
}
}
}
}
}
} ProgrammaticallyWithin a theme's register_block_style(
array( 'core/group', 'core/columns' ),
array(
'name' => 'green',
'label' => __( 'Green' ),
'style_data' => array(
'color' => array(
'background' => '#4f6f52',
'text' => '#d2e3c8',
),
'blocks' => array(
'core/group' => array(
'color' => array(
'background' => '#739072',
'text' => '#e3eedd',
),
),
),
'elements' => array(
'link' => array(
'color' => array(
'text' => '#ead196',
),
':hover' => array(
'color' => array(
'text' => '#ebd9b4',
),
),
),
),
),
)
) Via Theme Style Variations (Not Recommended)This approach has been enabled as a temporary means to facilitate ergonomic definitions of shared block style variations through theme style variations. It is being flagged here for transparency however it will likely be deprecated soon as the Global Styles architecture is updated to address growing complexity and simplify its mental model. More details on what's ahead for Global Styles can be found in this issue. Shared block style variations can be defined via Additionally, a new translatable title property has been added here to mirror the capabilities of the theme.json partial files outlined above. The key for the variation correlates to the {
"$schema": "https://schemas.wp.org/trunk/theme.json",
"version": 3,
"title": "Theme Style Variation",
"styles": {
"variations": {
"variation-a": {
"color": {
"background": "#eed8d3",
"text": "#201819"
},
"elements": {
"heading": {
"color": {
"text": "#201819"
}
},
},
"blocks": {
"core/group": {
"color": {
"background": "#825f58",
"text": "#eed8d3"
},
"elements": {
"heading": {
"color": {
"text": "#eed8d3"
}
}
}
}
}
},
}
}
} Backwards CompatibilityAs the Section Styles feature was implemented via extensions to block style variations rather than as a replacement, existing block style variations will continue to work as before. LimitationsThe following limitations for block style variations in WordPress 6.6 should be noted:
What's Next?The Global Styles UI for block style variations will be updated to facilitate the customization of all available styles for inner elements and block types. This includes potentially enhancing the Style Book to support block style variations. Another future enhancement is the possible support for settings per block style variations. Useful Links
|
…g section styling (WordPress#57908) Co-authored-by: aaronrobertshaw <aaronrobertshaw@git.wordpress.org> Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org> Co-authored-by: ramonjd <ramonopoly@git.wordpress.org> Co-authored-by: talldan <talldanwp@git.wordpress.org> Co-authored-by: youknowriad <youknowriad@git.wordpress.org> Co-authored-by: ellatrix <ellatrix@git.wordpress.org> Co-authored-by: SaxonF <saxonafletcher@git.wordpress.org> Co-authored-by: richtabor <richtabor@git.wordpress.org> Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org> Co-authored-by: cbirdsong <cbirdsong@git.wordpress.org> Co-authored-by: bacoords <bacoords@git.wordpress.org> Co-authored-by: getdave <get_dave@git.wordpress.org> Co-authored-by: colorful-tones <colorful-tones@git.wordpress.org> Co-authored-by: hanneslsm <hanneslsm@git.wordpress.org> Co-authored-by: andrewserong <andrewserong@git.wordpress.org> Co-authored-by: kevin940726 <kevin940726@git.wordpress.org> Co-authored-by: ajlende <ajlende@git.wordpress.org> Co-authored-by: MaggieCabrera <onemaggie@git.wordpress.org> Co-authored-by: scruffian <scruffian@git.wordpress.org>
getBlockTypes(), | ||
getBlockStyles, | ||
clientId | ||
); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is this? Why are we getting all "block selectors" (not sure what this is but it seems more than just variation related stuff), and for all block types?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From memory, we're getting all the block selectors as block style variations can define styles for inner blocks. Those blocks can define custom selectors for certain features. For example, border styles might be applied to an inner element like in the Image block for example.
So the variations styles need to also apply the inner block styles correctly using those same selectors retrieved normally.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could be only get the block types of the blocks as inner blocks?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That might be an optimisation we can make. At the moment, I'm a little preoccupied with updates over in #62712
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did this in #57908
I've updated the dev note comment in to be in line with updates in #62712 that should be landing soon. I'll update the make post accordingly too. |
function useBlockProps( { name, className, clientId } ) { | ||
const { getBlockStyles } = useSelect( blocksStore ); | ||
|
||
const registeredStyles = getBlockStyles( name ); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Calling a store selector during render could lead to some unexpected results.
The hook isn't subscribed to block style updates, and it will only fetch new values when the consumer or useBlockSyleVariation
triggers a re-render.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would there be a risk when new styles are registered/deregistered?
I don't know yet if it's worth it, but I think by refactoring getBlockSelectors
or creating a new function that accepts a single block type and registeredStyles
(and not the function), it'd be possible to call getBlockStyles
in the store subscription callback, e.g.,
const blockType = useMemo(
() =>
getBlockTypes().find(
( { name: blockName } ) => blockName === name
),
[ name ]
);
const { registeredStyles } = useSelect(
( select ) => {
const { getBlockStyles } = select( blocksStore );
return {
registeredStyles: getBlockStyles( name ),
};
},
[ name ]
);
...
const blockSelectors = getBlockSelectorForBlock(
blockType,
registeredStyles,
clientId
);
Addresses:
Related:
What?
#56540 aimed to render block style variation styles within the overall global styles stylesheet. This was problematic in that it required increasing specificity of element styles applied to block instances as well as being unable to be reliably nested.
The idea in this PR is to reduce the specificity as far as possible for block style variations and their inner element and block type styles. Then generate stylesheets for the application of these variations in the order of their application (parent > child > grandchild etc) such that the correct cascade is maintained. This is so block style variations can be applied on nested blocks.
Why?
The ability to style entire sections of a page without having to tediously reapply the same sets of styles is greatly desired. Block style variations seemed to be the best mechanism for defining these styles.
How?
blockTypes
property.blockTypes
key, it will be treated as a theme style variation for backwards compatibility./styles
that have"block"
within its defined scopesstyles.blocks.variations
property of a theme's primary theme.json filestyles.blocks.variations
property of a theme style variation partial theme.jsonstyles.blocks.core/group.variations
block-style-variations
block support has been added that injects a unique CSS class per block instance application of a block style variation.useBlockProps
to generate the styles on the editor side so they update correctly upon application to blocks./styles
This PR is a bit of a monster but would be much more difficult to test properly if split up. It will be easier to review the code changes per commit as they were deliberately made in smaller conceptual chunks.
Next Steps
There are two main follow-ups needed and both will be explored separately once this initial iteration has merged.
/styles
directoryTesting Instructions
Setting up test block style variations
There are several methods by which block style variations can be added.
gutenberg_register_block_style
/styles
subdirectorystyles.blocks.variations
Programmatically
Within a theme's functions.php or a plugin, a call can me made to the new extended version of
gutenberg_register_block_style
, passing it an array of block types the variation can be used with as well as a style object definition the variation's styles. The theme.json resolver will absorb any styles registered via this approach into the theme's theme.json data.Example usage
Standalone partial files
These partials will live (for now) under the/block-styles
directory in the theme directory.Block style variation theme.json partial files share the same directory as theme style variations, i.e.
/styles
in the theme directory.These theme.json partial files will support a new
blockTypes
property.The new
blockTypes
property serves a dual purpose. Firstly, it defines an array of block types the variation is available for. Secondly, if it is a non-empty array, it flags a variation as a block style variation.These block style variations will be automatically registered and absorbed into the theme's theme.json data by the resolver.
Example
Defined by theme style variations
As theme style variations are essentially theme.json partials themselves that are copied into the user origin's theme.json data, they can't easily pull into other partials for block style variations. This lead to reintroducing the
styles.blocks.variations
property for theme.json.Similar to the standalone block style variations, each definition under
styles.blocks.variations
will require a new propertyblockTypes
to define the block types that get the variation.Example
Things to test
Testing Instructions for Keyboard
Screenshots or screencast
Screen.Recording.2024-05-28.at.6.36.06.PM.mp4
Quickly hacked together TT4 child theme used in above demo.